@metarhia/common

Metarhia Common Library

Namespace: api.common in Impress Application Server

Installation

$ npm install @metarhia/common

API

splitAt(index, array)

• index: <number> index defining end of first part and start of second
• array: <Array> to be split

Returns: <Array> tuple with two parts of the array

Split array into two parts

shuffle(arr)

• arr: <Array>

Returns: <Array>

Shuffle an array

range(from, to)

• from: <number> range start
• to: <number> range end

Returns: <Array>

Generate int array from given range

Example:

range(1, 5);

Result:

[1, 2, 3, 4, 5];

sequence(seq[, max])

• seq: <Array>
• max: <number> (optional), max

Returns: <Array>

Generate int array from sequence syntax

Example:

list: sequence([81, 82, 83]);

Result:

[81, 82, 83];

Example:

range from..to: sequence([81,,83]) = [81, 82, 83];

Result:

[81, 82, 83];

Example:

range from..count: sequence([81, [3]]) = [81, 82, 83];

Result:

[81, 82, 83];

Example:

range from..max-to: sequence([81, [-2]], 5) = [81, 82, 83];

Result:

[81, 82, 83];

last(arr)

• arr: <Array>

Returns: <any> element

Get last element of array

pushSame(arr, n, value)

• arr: <Array>
• n: <number>
• value: <any>

Returns: <number> new value of arr.length

Push single value multiple times

checkLogin(login, required[, optional])

• login: <string> login to test
• required: <Array> required tests configs
• optional: <Array> optional tests configs, defalult: []

Returns: <AuthenticationStrength>

Function that tests the login

checkPassword(password, required[, optional])

• password: <string> password to test
• required: <Array> required tests configs
• optional: <Array> optional tests configs, default: []

Returns: <AuthenticationStrength>

Function that tests the password

checkLoginPassword(login, password, required[, optional])

• login: <string> login to test
• password: <string> password to test
• required: <Array> required tests configs
• optional: <Array> optional tests configs, default: []

Returns: <AuthenticationStrength>

Function that tests the login with password

class BTree

BTree.prototype.constructor(degree = DEFAULT_DEGREE)

BTree.prototype.get(key)

BTree.prototype.set(key, data)

BTree.prototype.iterator(start, finish)

BTree.prototype.remove(key)

cache()

Returns: <Cache>

Create Cache, enhanced Map

class Cache

Cache.super_()

Cache.prototype.constructor()

Cache.prototype.add(key, val)

• key: <string> key
• val: <any> associated value

Add key-value pair to cache

Cache.prototype.del(key)

• key: <string> key

Delete cache element

Cache.prototype.clr(prefix[, fn])

• prefix: <string> to compare with beginning of the key
• fn: <Function> (optional)
  • key: <string> key
  • val: <any> associative value to be called on each key

Clear cache elements that start with prefix

falseness()

Returns: <boolean> always false

Empty function

trueness()

Returns: <boolean> always true

Empty function

emptiness()

Empty function

nop(callback)

• callback: <Function> callback to be called with (null)

Empty asynchronous callback-last single-argument function

noop(empty, callback)

• empty: <any> incoming value to be ignored
• callback: <Function> callback to be called with (null, null)

Empty asynchronous callback-last double-argument function

once([fn])

• fn: <Function> (optional)

Returns: <Function> function(...args) wrapped callback

• args: <Array>

Wrap function: call once, not null

cb(...args)

unsafeCallback(args)

• args: <Array> arguments

Returns: <Function>|<null> callback if any

Extract callback function

It's unsafe: may return null, allows multiple calls

extractCallback(...args)

cbUnsafe(...args)

safeCallback(args)

• args: <Array> arguments

Returns: <Function> callback or common.emptiness if there is no callback

Extract callback

cbExtract(...args)

requiredCallback(args)

• args: <Array> arguments

Returns: <Function> extracted callback

Extract callback

Throws: <TypeError> if there is no callback

onceCallback(args)

• args: <Array> arguments

Returns: <Function> callback or common.emptiness if there is no callback

Extract callback and make it safe

Wrap callback with once()

safeFunction(fn)

• fn: <Function>

Returns: <Function> function or common.emptiness if fn is not a function

Check function and make it safe

unsafeFunction(fn)

• fn: <Function>

Returns: <Function>|<null> function or null if fn is not a function

Check function

id(x)

• x: <any> incoming value which will be returned

Returns: <any> incoming value

Identity function

asyncId(x, callback)

• x: <any> incoming value which will be returned into the callback
• callback: <Function> callback to be called with first argument
  • err: <null>
  • data: <any>

Async identity function

isScalar(value)

• value: <any>

Returns: <boolean>

Check if value is scalar

copy(ds)

• ds: <Object[]> source dataset to be copied

Returns: <Object[]>

Copy dataset (copy objects to new array)

clone(obj)

• obj: <Object>|<Array>

Returns: <Object>|<Array>

Clone object or array

duplicate(obj)

• obj: <Object>|<Array>

Returns: <Object>|<Array>

Duplicate object or array (properly handles prototype and circular links)

getByPath(data, dataPath)

• data: <Object>
• dataPath: <string> dot-separated path

Returns: <any> value

Read property by dot-separated path

setByPath(data, dataPath, value)

• data: <Object>
• dataPath: <string> dot-separated path
• value: <any> new value

Set property by dot-separated path

deleteByPath(data, dataPath)

• data: <Object>
• dataPath: <string> dot-separated path

Returns: <boolean>

Delete property by dot-separated path

merge(...args)

• args: <Array[]> arrays with elements to be merged

Returns: <Array>

Distinctly merge multiple arrays

mergeObjects(merger, ...objs)

• merger: <Function>
• objs: <Object[]> objects to be merged

Returns: <Object>

Merge multiple objects with merger

class Enum

Enum.from(...args)

Enum.NaE()

Enum.prototype.constructor(...args)

forwardEvents(from, to[, events])

• from: <EventEmitter> to listen for event
• to: <EventEmitter> to emit event on
• events: <string>|<Object>|<string[]> (optional), events names

Forward events from one EventEmitter to another

Example:

forwardEvents(from, to);

Example:

forwardEvents(from, to, 'eventName');

Example:

forwardEvents(from, to, { eventName: 'newEventName' });

Example:

forwardEvents(from, to, ['eventName1', 'eventName2']);

emitter()

Returns: <EventEmitter>

Create EnhancedEmitter, enhanced EventEmitter

with wildcard and forward method

class EnhancedEmitter

EnhancedEmitter.super_()

EnhancedEmitter.prototype.constructor()

EnhancedEmitter.prototype.emit(...args)

• args: <Array> arguments to be passed

Call listener with provided arguments

EnhancedEmitter.prototype.forward(to, events)

• to: <EventEmitter> to emit event on
• events: <string>|<Object>|<string[]> events names

Forward events from one EventEmitter to another

class Flags

Flags.from(...args)

Flags.prototype.constructor(...args)

partial(fn, ...args)

• fn: <Function>
• args: <Array> arguments to be applied

Returns: <Function> function(...rest)

• rest: <Array> arguments

Partially apply arguments to function

omap(mapFn, obj)

• mapFn: <Function> to apply to every field value
• obj: <Object> which fields used for mapping

Returns: <Object> with same reference but with transformed fields

Map object fields with provided function

compose(...fns)

• fns: <Array> functions to be composed

Returns: <Function> function(...args), composed

• args: <Array> arguments to be passed to the first function

Compose multiple functions into one

maybe(fn, defVal[, value])

• fn: <Function>
• defVal: <any> default value
• value: <any> (optional), value

Returns: <any> result of fn or defVal

Apply given function to value or default value

zip(...arrays)

• arrays: <Array[]> arrays to be zipped

Returns: <Array> length is minimal of input arrays length, element with index i of resulting array is array with elements with index i from input array

Zip several arrays into one

replicate(count, elem)

• count: <number> new array length
• elem: <any> value to replicate

Returns: <Array> replicated

Create array of replicated values

zipWith(fn, ...arrays)

• fn: <Function> for zipping elements with index i
• arrays: <Array[]> arrays to be zipped

Returns: <Array> zipped, element with index i of resulting array is result of fn called with arguments from arrays

Zip arrays using specific function

curryUntil(condition, fn, ...args)

• condition: <Function> returns: <boolean>
  • argsI: <Array> arguments for i-th currying
  • argsParts: <Array> of args given for currying from first to i-th currying
• fn: <Function> to be curried
• args: <Array> arguments for fn

Returns: <Function> function(...args), curried

• args: <Array> arguments

Curry function until the condition is met

curryN(fn, count, ...args)

• fn: <Function> to be curried
• count: <number> of times function should be curried
• args: <Array> arguments for first currying

Returns: <Function> curried given times count

Curry fn count times, first curry uses args for first currying

curryTwice(fn)

• fn: <Function> to be curried

Returns: <Function> to pass arguments that returns curried fn

Curry function curry with fn

curry(fn, ...param)

• fn: <Function> to be curried
• param: <Array> arguments to the function

Returns: <Function> function(...args), curried

Curry function with given arguments

applyArgs(...args)

• args: <Array> arguments to save in closure

Returns: <Function> returns: <any>, result of fn(...args)

• fn: <Function> to be applied saved arguments

Apply arguments

either(fn)

• fn: <Function> to be called

Returns: <Function> function(...args), returns: <any>, result of fn(arg), where arg - first valid element of args

• args: <Array> arguments to iterate

Get first not errored result of fn

Throws: <Error> if fn throws it

restLeft(fn)

• fn: <Function> function(args, ...namedArgs, callback)
  • args: <Array> rest of spreadArgs created by excluding namedArgs
  • namedArgs: <Array> first values of spreadArgs, length is based upon interface of fn
  • callback: <Function> callback, last argument of spreadArgs

Returns: <Function> function(...spreadArgs)

• spreadArgs: <Array> arguments to be added

Rest left, transform function

mkdirp(dir, mode, cb)

rmdirp(dir, cb)

generateKey(length, possible)

• length: <number> key length
• possible: <string> with possible characters

Returns: <string> key

Generate random key

generateGUID()

Returns: <string> GUID

Generate an RFC4122-compliant GUID (UUID v4)

generateSID(config)

• config: <Object> { length, characters, secret }

Returns: <string> SID

Generate random SID

Deprecated: this method will be removed in the next major versions. Use generateToken() instead.

crcSID(config, key)

• config: <Object> { secret }
• key: <string> SID key

Returns: <string> CRC

Calculate SID CRC

Deprecated: this method will be removed in the next major versions. Use crcToken() instead.

validateSID(config, sid)

• config: <Object> { secret }
• sid: <string> session id

Returns: <boolean>

Validate SID

Deprecated: this method will be removed in the next major versions. Use validateToken() instead.

generateToken(secret, characters, length)

• secret: <string>
• characters: <string>
• length: <number>

Returns: <string> token

Generate random Token

crcToken(secret, key)

• secret: <string>
• key: <string>

Returns: <string> crc

Calculate Token crc

validateToken(secret, token)

• secret: <string>
• token: <string>

Returns: <boolean>

Validate Token

hash(password, salt)

• password: <string>
• salt: <string>

Returns: <string> hash

Calculate hash with salt

validateHash(hashValue, password, salt)

• hashValue: <string>
• password: <string>
• salt: <string>

Returns: <boolean>

Validate hash

generateStorageKey()

Returns: <string[]> [folder1, folder2, code]

Generate file storage key

idToChunks(id)

• id: <number>

Returns: <Array> minimal length is 2 which contains hex strings with length of 4

Convert id to array of hex strings

idToPath(id)

• id: <number>

Returns: <string>

Convert id to file path

pathToId(path)

• path: <string>

Returns: <number>

Convert file path to id

class Int64

Int64.zero()

Int64.one()

Int64._conversion(value)

Convert signed to 2's complement representation and vise versa

Int64.add(a, b)

Int64.sub(a, b)

Int64.cmp(a, b)

Int64._division(n, d)

Int64.div(a, b)

Int64.mod(a, b)

Int64.mult(a, b)

Int64.and(a, b)

Int64.or(a, b)

Int64.not(a)

Int64.xor(a, b)

Int64.shiftRight(a, b)

Int64.shiftLeft(a, b)

Int64.prototype.constructor(value)

Int64.prototype.toInt32()

Int64.prototype.toUint32()

Int64.prototype.add(b)

Int64.prototype.sub(b)

Int64.prototype.and(b)

Int64.prototype.or(b)

Int64.prototype.not()

Int64.prototype.xor(b)

Int64.prototype.shiftRightLogical(b)

Int64.prototype.shiftRightArithmetic(b)

Int64.prototype.shiftRight(b)

Int64.prototype.shiftLeft(b)

Int64.prototype.inc()

Int64.prototype.dec()

Int64.prototype.toString(radix = 10)

Int64.prototype.toJSON()

Int64.prototype.toPostgres()

class Iterator

Iterator.range(start, stop[, step])

• start: <number>
• stop: <number>
• step: <number> (optional), default: 1

Returns: <Iterator>

Create iterator iterating over the range

Iterator.prototype.constructor(base)

Iterator.prototype.next()

Iterator.prototype.count()

Iterator.prototype.each(fn, thisArg)

Iterator.prototype.forEach(fn, thisArg)

Iterator.prototype.every(predicate, thisArg)

Iterator.prototype.find(predicate, thisArg)

Iterator.prototype.includes(element)

Iterator.prototype.reduce(reducer, initialValue)

Iterator.prototype.some(predicate, thisArg)

Iterator.prototype.someCount(predicate, count, thisArg)

Iterator.prototype.collectTo(CollectionClass)

Iterator.prototype.collectWith(obj, collector)

Iterator.prototype.toArray()

Iterator.prototype.map(mapper, thisArg)

Iterator.prototype.filter(predicate, thisArg)

Iterator.prototype.flat(depth = 1)

Iterator.prototype.flatMap(mapper, thisArg)

Iterator.prototype.zip(...iterators)

Iterator.prototype.chain(...iterators)

Iterator.prototype.take(amount)

Iterator.prototype.takeWhile(predicate, thisArg)

Iterator.prototype.skip(amount)

Iterator.prototype.enumerate()

Iterator.prototype.join(sep = ', ', prefix = '', suffix = '')

iter(base)

cryptoPrefetcher(bufSize, valueSize)

• bufSize: <number> size in bytes of the buffer to preallocate
• valueSize: <number> size in bytes of the produced chunks

Create prefetcher to use when crypto.randomBytes is required to generate

multiple same-size values. bufSize must be a multiple of valueSize for this to work.

random(min, max)

• min: <number> range start
• max: <number> range end

Returns: <number>

Generate random integer value in given range

cryptoRandom()

Returns: <number>

Generate random number in the range from 0 inclusive up to

but not including 1 (same as Math.random), using crypto-secure number generator.

methods(iface)

• iface: <Object> to be introspected

Returns: <string[]> method names

List method names

properties(iface)

• iface: <Object> to be introspected

Returns: <string[]> property names

List property names

ip2int(...args)

ipToInt([ip])

• ip: <string> (optional), default: '127.0.0.1', IP address

Returns: <number>

Convert IP string to number

localIPs()

Returns: <string[]>

Get local network interfaces

parseHost(host)

• host: <string> host or empty string, may contain :port

Returns: <string> host without port but not empty

Parse host string

inherits(child, base)

override(obj, fn)

• obj: <Object> containing method to override
• fn: <Function> name will be used to find method

Override method: save old to fn.inherited

Previous function will be accessible by obj.fnName.inherited

mixin(target, source)

• target: <Object> mixin to target
• source: <Object> source methods

Mixin for ES6 classes without overriding existing methods

class Pool

Pool.prototype.constructor(factory = null)

Pool.prototype.put(value)

Pool.prototype.get()

sortComparePriority(priority, s1, s2)

• priority: <string[]> with priority
• s1: <string> to compare
• s2: <string> to compare

Returns: <number>

Compare for array.sort with priority

Example:

files.sort(common.sortComparePriority);

sortCompareDirectories(a, b)

• a: <string> to compare
• b: <string> to compare

Returns: <number>

Compare for array.sort, directories first

Example:

files.sort(sortCompareDirectories);

sortCompareByName(a, b)

• a: <Object> { name } to compare
• b: <Object> { name } to compare

Returns: <number>

Compare for array.sort

Example:

files.sort(sortCompareByName);

subst(tpl, data, dataPath, escapeHtml)

• tpl: <string> template body
• data: <Object> hash, data structure to visualize
• dataPath: <string> current position in data structure
• escapeHtml: <boolean> escape html special characters if true

Returns: <string>

Substitute variables

htmlEscape(content)

• content: <string> to escape

Returns: <string>

Escape html characters

Example:

htmlEscape('5>=5') = '5<=5';

fileExt(fileName)

• fileName: <string> file name

Returns: <string>

Extract file extension in lower case without dot

Example:

fileExt('/dir/file.txt');

Result:

'txt';

removeExt(fileName)

• fileName: <string> file name

Returns: <string>

Remove file extension from file name

Example:

fileExt('file.txt');

Result:

'file';

spinalToCamel(name)

• name: <string>

Returns: <string>

Convert spinal case to camel case

escapeRegExp(s)

• s: <string>

Returns: <string>

Escape regular expression control characters

Example:

escapeRegExp('/path/to/res?search=this.that');

newEscapedRegExp(s)

• s: <string>

Returns: <RegExp>

Generate escaped regular expression

addTrailingSlash(s)

• s: <string>

Returns: <string>

Add trailing slash at the end if there isn't one

stripTrailingSlash(s)

• s: <string>

Returns: <string>

Remove trailing slash from string

dirname(filePath)

• filePath: <string>

Returns: <string>

Get directory name with trailing slash from path

capitalize(s)

• s: <string>

Returns: <string>

Capitalize string

between(s, prefix, suffix)

• s: <string> source
• prefix: <string> before needed fragment
• suffix: <string> after needed fragment

Returns: <string>

Extract substring between prefix and suffix

removeBOM(s)

• s: <string> possibly starts with BOM

Returns: <string>

Remove UTF-8 BOM

arrayRegExp(items)

• items: <string[]>

Returns: <RegExp>

Generate RegExp from array with '*' wildcards

Example:

['/css/*', '/index.html'];

section(s, separator)

• s: <string>
• separator: <string> or char

Returns: <string[]>

Split string by the first occurrence of separator

Example:

rsection('All you need is JavaScript', 'is');

Result:

['All you need ', ' JavaScript'];

rsection(s, separator)

• s: <string>
• separator: <string> or char

Returns: <string[]>

Split string by the last occurrence of separator

Example:

rsection('All you need is JavaScript', 'a');

Result:

['All you need is Jav', 'Script'];

split(s[, separator[, limit]])

• s: <string>
• separator: <string> (optional), default: ','
• limit: <number> (optional), default: -1, max length of result array

Returns: <string[]>

Split string by multiple occurrence of separator

Example:

split('a,b,c,d');

Result:

['a', 'b', 'c', 'd'];

Example:

split('a,b,c,d', ',', 2);

Result:

['a', 'b'];

rsplit(s[, separator[, limit]])

• s: <string>
• separator: <string> (optional), default: ','
• limit: <number> (optional), default: -1, max length of result array

Returns: <string[]>

Split string by multiple occurrences of separator

Example:

split('a,b,c,d', ',', 2);

Result:

['c', 'd'];

normalizeEmail(email)

• email: <string> email address to normalize

Returns: <string> normalized email address

Normalize email address according to OWASP recommendations

isTimeEqual(time1, time2)

• time1: <string> time or milliseconds
• time2: <string> time or milliseconds

Returns: <boolean>

Compare time1 and time2

Example:

isTimeEqual(sinceTime, buffer.stats.mtime);

nowDate([date])

• date: <Date> (optional), default: new Date()

Returns: <string>

Get current date in YYYY-MM-DD format

nowDateTime([date])

• date: <Date> (optional), default: new Date()

Returns: <string>

Get current date in YYYY-MM-DD hh:mm format

class Uint64

Uint64.add(a, b)

Uint64.sub(a, b)

Uint64.mult(a, b)

Uint64.cmp(a, b)

Uint64._division(n, d)

Uint64.div(a, b)

Uint64.mod(a, b)

Uint64.and(a, b)

Uint64.or(a, b)

Uint64.not(a)

Uint64.xor(a, b)

Uint64.shiftRight(a, b)

Uint64.shiftLeft(a, b)

Uint64.prototype.constructor(value)

Uint64.prototype.toUint32()

Uint64.prototype.add(b)

Uint64.prototype.sub(b)

Uint64.prototype.and(b)

Uint64.prototype.or(b)

Uint64.prototype.not()

Uint64.prototype.xor(b)

Uint64.prototype.shiftRight(b)

Uint64.prototype.shiftLeft(b)

Uint64.prototype.inc()

Uint64.prototype.dec()

Uint64.prototype.toString(radix = 10)

Uint64.prototype.toJSON()

Uint64.prototype.toPostgres()

duration(s)

• s: <string> duration syntax

Returns: <number> milliseconds

Parse duration to seconds

Example:

duration('1d 10h 7m 13s');

durationToString(n)

• n: <number> duration

Returns: <string>

Convert integer duration to string

bytesToSize(bytes)

• bytes: <number> size

Returns: <string>

Convert integer to string, representing data size in Kb, Mb, Gb, and Tb

sizeToBytes(size)

• size: <string> size

Returns: <number>

Convert string with data size to integer

deprecate(fn)

• fn: <Function>

Returns: <Function> wrapped with deprecation warning

• args: <Array> arguments to be passed to wrapped function

Wrap method to mark it as deprecated

alias(fn)

• fn: <Function>

Returns: <Function> wrapped with deprecation warning

• args: <Array> arguments to be passed to wrapped function

Wrap new method to mark old alias as deprecated

safe(fn)

• fn: <Function>

Returns: <Function> function(...args), wrapped with try/catch interception

• args: <Array> arguments to be passed to wrapped function

Make function raise-safe

callerFilename(depth = 0, stack = null)

callerFilepath(depth = 0, stack = null)

Contributors

See github for full contributors list